--- /dev/null
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!ENTITY version SYSTEM "../version.xml">
+]>
+<part id="deployment">
+ <title>Deployments</title>
+ <chapter id="deployment-intro">
+ <title>Overview</title>
+ <para>
+ Built on top of the OSTree versioning filesystem core is a layer
+ that knows how to deploy, parallel install, and manage Unix-like
+ operating systems (accessible via <command>ostree
+ admin</command>). The core content of these operating systems
+ are treated as read-only, but they transparently share storage.
+ </para>
+
+ <para>
+ A deployment is physically located at a path of the form
+ <filename
+ class='directory'>/ostree/deploy/<replaceable>osname</replaceable>/deploy/<replaceable>checksum</replaceable></filename>.
+ OSTree is designed to boot directly into exactly one deployment
+ at a time; each deployment is intended to be a target for
+ <literal>chroot()</literal> or equivalent.
+ </para>
+
+ </chapter>
+
+ <chapter id="deployment-osname">
+ <title>"osname": Group of deployments that share /var</title>
+ <para>
+ Each deployment is grouped in exactly one "osname". From
+ above, you can see that an osname is physically represented in
+ the <filename
+ class='directory'>/ostree/deploy/<replaceable>osname</replaceable></filename>
+ directory. For example, OSTree can allow parallel installing
+ Debian in <filename
+ class='directory'>/ostree/deploy/debian</filename> and Red Hat
+ Enterprise Linux in <filename
+ class='directory'>/ostree/deploy/rhel</filename> (subject to
+ operating system support, present released versions of these
+ operating systems may not support this).
+ </para>
+
+ <para>
+ Each osname has exactly one copy of the traditional Unix
+ <filename class='directory'>/var</filename>, stored physically
+ in <filename
+ class='directory'>/ostree/deploy/<replaceable>osname</replaceable>/var</filename>.
+ OSTree provides support tools for <command>systemd</command>
+ to create a Linux bind mount that ensures the booted
+ deployment sees the shared copy of <filename
+ class='directory'>/var</filename>.
+ </para>
+
+ <para>
+ OSTree does not touch the contents of <filename
+ class='directory'>/var</filename>. Operating system components
+ such as daemon services are required to create any directories
+ they require there at runtime (e.g. <filename
+ class='directory'>/var/cache/<replaceable>daemonname</replaceable></filename>),
+ and to manage upgrading data formats inside those directories.
+ </para>
+ </chapter>
+
+ <chapter id="deployment-contents">
+ <title>Contents of a deployment</title>
+ <para>
+ A deployment begins with a specific commit (represented as a
+ SHA256 hash) in the OSTree repository in <filename
+ class='directory'>/ostree/repo</filename>. This commit refers
+ to a filesystem tree that represents the underlying basis of a
+ deployment. For short, we will call this the "tree", to
+ distinguish it from the concept of a deployment.
+ </para>
+
+ <para>
+ First, the tree must include a kernel stored as <filename
+ class='directory'>/boot/vmlinuz-<replaceable>checksum</replaceable></filename>.
+ The checksum should be a SHA256 hash of the kernel contents;
+ it must be pre-computed before storing the kernel in the
+ repository. Optionally, the tree can contain an initramfs,
+ stored as <filename
+ class='directory'>/boot/initramfs-<replaceable>checksum</replaceable></filename>.
+ If this exists, the checksum must include both the kernel and
+ initramfs contents. OSTree will use this to determine which
+ kernels are shared. The rationale for this is to avoid
+ computing checksums on the client by default.
+ </para>
+
+ <para>
+ The deployment should not have a traditional UNIX <filename
+ class='directory'>/etc</filename>; instead, it should include
+ <filename class='directory'>/usr/etc</filename>. This is the
+ "default configuration". When OSTree creates a deployment, it
+ performs a 3-way merge using the <emphasis>old</emphasis>
+ default configuration, the active system's <filename
+ class='directory'>/etc</filename>, and the new default
+ configuration. In the final filesystem tree for a deployment
+ then, <filename class='directory'>/etc</filename> is a regular
+ writable directory.
+ </para>
+
+ <para>
+ Besides the exceptions of <filename
+ class='directory'>/var</filename> and <filename
+ class='directory'>/etc</filename> then, the rest of the
+ contents of the tree are checked out as hard links into the
+ repository. It's strongly recommended that operating systems
+ ship all of their content in <filename
+ class='directory'>/usr</filename>, but this is not a hard
+ requirement.
+ </para>
+ </chapter>
+
+ <chapter id="managing-boot">
+ <title>The system /boot</title>
+ <para>
+ While OSTree parallel installs deployments cleanly inside the
+ <filename class='directory'>/ostree</filename> directory,
+ ultimately it has to control the system's <filename
+ class='directory'>/boot</filename> directory. The way this
+ works is via the <ulink
+ url="http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/">boot
+ loader specification</ulink>, which is a standard for
+ bootloader-independent drop-in configuration files.
+ </para>
+ <para>
+ When a tree is deployed, it will have a configuration file
+ generated of the form <filename
+ class='directory'>/boot/loader/entries/ostree-<replaceable>osname</replaceable>-<replaceable>checksum</replaceable>.<replaceable>serial</replaceable>.conf</filename>.
+ This configuration file will include a special
+ <literal>ostree=</literal> kernel argument that allows the
+ initramfs to find (and <literal>chroot()</literal> into) the
+ specified deployment.
+ </para>
+
+ <para>
+ At present, not all bootloaders implement the BootLoaderSpec,
+ so OSTree contains code for some of these to regenerate native
+ config files (such as
+ <filename>/boot/syslinux/syslinux.conf</filename> based on the
+ entries.
+ </para>
+
+ </chapter>
+</part>
projects / ostree.git / commitdiff